<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Open Channel</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="kvaser.gif"/></td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('page_user_guide_chips_channels.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Open Channel </div>  </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#section_user_guide_init_sel_channel_can">Open as CAN</a></li>
<li class="level1"><a href="#section_user_guide_init_sel_channel_canfd">Open as CAN FD</a></li>
<li class="level1"><a href="#section_user_guide_init_sel_channel_close">Close Channel</a></li>
<li class="level1"><a href="#section_user_guide_check_channel_capabilities">Check Channel Capabilities</a></li>
<li class="level1"><a href="#section_user_guide_init_bit_rate_can_tq">Set CAN Bitrate</a><ul><li class="level2"><a href="#section_user_guide_init_bit_rate_can_specify_tq">Specifying Bit Timing Parameters</a></li>
<li class="level2"><a href="#section_user_guide_init_bit_rate_can_predefined">Using Predefined Bitrate Constants</a></li>
</ul>
</li>
<li class="level1"><a href="#section_user_guide_init_bit_rate_canfd_tq">Set CAN FD Bitrate</a><ul><li class="level2"><a href="#section_user_guide_init_bit_rate_canfd_specify_tq">Specifying Bit Timing Parameters</a></li>
<li class="level2"><a href="#section_user_guide_init_bit_rate_canfd_predefined">Using Predefined Bitrate Constants</a></li>
</ul>
</li>
<li class="level1"><a href="#section_user_guide_init_driver_modes">CAN Driver Modes</a></li>
<li class="level1"><a href="#code_sample">Code Sample</a></li>
<li class="level1"><a href="#section_user_guide_init_bit_rate_legacy">Legacy Functions</a><ul><li class="level2"><a href="#section_user_guide_init_bit_rate_can">Set CAN Bitrate</a></li>
<li class="level2"><a href="#section_user_guide_init_bit_rate_canfd">Set CAN FD Bitrate</a></li>
</ul>
</li>
</ul>
</div>
<div class="textblock"><p>Once we have called <a class="el" href="group__can__general.html#gaff1ec1d3416d3bdd56336a7b9ac008b1">canInitializeLibrary()</a> to enumerate the connected Kvaser CAN devices, the next call is likely to be a call to <a class="el" href="group___c_a_n.html#gac377d182232fb4ec2fed881c2b9ab300">canOpenChannel()</a>, which returns a handle to a specific CAN circuit. This handle is then used to all subsequent calls to the library. The <a class="el" href="group___c_a_n.html#gac377d182232fb4ec2fed881c2b9ab300">canOpenChannel()</a> function takes two arguments, the first of which is the number of the desired channel, the second argument is modifier flags <a class="el" href="canlib_8h.html#canOPEN_xxx">canOPEN_xxx</a>.</p>
<p><a class="el" href="group___c_a_n.html#gac377d182232fb4ec2fed881c2b9ab300">canOpenChannel()</a> may return several different error codes, one of which is <a class="el" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7a55c8bbcb0145b27275508325ece58a1c">canERR_NOTFOUND</a>. This means that the channel specified in the first parameter was not found, or that the flags passed to <a class="el" href="group___c_a_n.html#gac377d182232fb4ec2fed881c2b9ab300">canOpenChannel()</a> is not applicable to the specified channel.</p>
<h1><a class="anchor" id="section_user_guide_init_sel_channel_can"></a>
Open as CAN</h1>
<p>No special <a class="el" href="canlib_8h.html#canOPEN_xxx">canOPEN_xxx</a> modifier flag is needed in the flags argument to <a class="el" href="group___c_a_n.html#gac377d182232fb4ec2fed881c2b9ab300">canOpenChannel()</a> when opening a channel in CAN mode.</p>
<div class="fragment"><div class="line">hnd = <a class="code" href="group___c_a_n.html#gac377d182232fb4ec2fed881c2b9ab300">canOpenChannel</a>(channel_number, 0);</div></div><!-- fragment --><p><b>Example</b>. This example opens channel 0 for exclusive usage by this application.</p>
<div class="fragment"><div class="line"><a class="code" href="canlib_8h.html#a75f2e3a4c7b1e47c8c6b25b76975b510">CanHandle</a> hnd;</div><div class="line">hnd = <a class="code" href="group___c_a_n.html#gac377d182232fb4ec2fed881c2b9ab300">canOpenChannel</a>(0, <a class="code" href="canlib_8h.html#afacd9e186d273d0dc24956ea0d433822">canOPEN_EXCLUSIVE</a>);</div><div class="line"><span class="keywordflow">if</span> (hnd &lt; 0) {</div><div class="line">    printf(<span class="stringliteral">&quot;Open failed, stat=%d\n&quot;</span>, hnd);</div><div class="line">}</div></div><!-- fragment --><p>When opening a channel as CAN, use <a class="el" href="group___c_a_n.html#ga50f169c6f9dd6df93b17c322e8e4fd00">canSetBusParamsTq()</a> to specify bus parameters. Instructions and examples are found below.</p>
<h1><a class="anchor" id="section_user_guide_init_sel_channel_canfd"></a>
Open as CAN FD</h1>
<p>To open a channel in CAN FD mode, either <a class="el" href="canlib_8h.html#a10aad075bfb9891aa98cf3c131977dc3">canOPEN_CAN_FD</a> or <a class="el" href="canlib_8h.html#a692d91db67e06e0c11e9076141319e35">canOPEN_CAN_FD_NONISO</a> needs to be given in the flags argument to <a class="el" href="group___c_a_n.html#gac377d182232fb4ec2fed881c2b9ab300">canOpenChannel()</a>.</p>
<div class="fragment"><div class="line">hnd = <a class="code" href="group___c_a_n.html#gac377d182232fb4ec2fed881c2b9ab300">canOpenChannel</a>(channel_number, <a class="code" href="canlib_8h.html#a10aad075bfb9891aa98cf3c131977dc3">canOPEN_CAN_FD</a>);</div></div><!-- fragment --><p><b>Example</b>. This example opens channel 0 in CAN FD mode for exclusive usage by this application.</p>
<div class="fragment"><div class="line"><a class="code" href="canlib_8h.html#a75f2e3a4c7b1e47c8c6b25b76975b510">CanHandle</a> hnd;</div><div class="line">hnd = <a class="code" href="group___c_a_n.html#gac377d182232fb4ec2fed881c2b9ab300">canOpenChannel</a>(0, <a class="code" href="canlib_8h.html#a10aad075bfb9891aa98cf3c131977dc3">canOPEN_CAN_FD</a> | <a class="code" href="canlib_8h.html#afacd9e186d273d0dc24956ea0d433822">canOPEN_EXCLUSIVE</a>);</div><div class="line"><span class="keywordflow">if</span> (hnd &lt; 0) {</div><div class="line">    printf(<span class="stringliteral">&quot;Open failed, stat=%d\n&quot;</span>, hnd);</div><div class="line">}</div></div><!-- fragment --><p>When opening a channel as CAN FD, use <a class="el" href="group___c_a_n.html#ga4beeb28ede2e21a2988076e66f873723">canSetBusParamsFdTq()</a> to specify bus parameters. Instructions and examples are found below.</p>
<h1><a class="anchor" id="section_user_guide_init_sel_channel_close"></a>
Close Channel</h1>
<p>Closing a channel is done using <a class="el" href="group___c_a_n.html#ga49525373a4d08d93c651ec10f79dd36b">canClose()</a>. If no other handles are referencing the same CANlib channel, the channel is taken off bus. The handle can not be used for further references to the channel, so any variable containing this handle should be set to <a class="el" href="canlib_8h.html#ad1f2b460c7780224a9dbc0f8f8a4918a">canINVALID_HANDLE</a>.</p>
<div class="fragment"><div class="line"><a class="code" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7">canStatus</a> stat = <a class="code" href="group___c_a_n.html#ga49525373a4d08d93c651ec10f79dd36b">canClose</a>(hnd);</div><div class="line"><span class="keywordflow">if</span> (stat &lt; 0) {</div><div class="line">    printf(<span class="stringliteral">&quot;Close failed.&quot;</span>);</div><div class="line">}</div><div class="line">hnd = <a class="code" href="canlib_8h.html#ad1f2b460c7780224a9dbc0f8f8a4918a">canINVALID_HANDLE</a>;</div></div><!-- fragment --><h1><a class="anchor" id="section_user_guide_check_channel_capabilities"></a>
Check Channel Capabilities</h1>
<p>Channel specific information and capabilities can be obtained by a call to <a class="el" href="group___c_a_n.html#ga909e5c14b09fe76bad280475138d503e">canGetHandleData()</a> or <a class="el" href="group__can__general.html#gab9552d1a588b0dbc144b097acba017b2">canGetChannelData()</a>. What information to receive from the channel is specified by passing an argument of type <a class="el" href="canlib_8h.html#canCHANNELDATA_xxx">canCHANNELDATA_xxx</a>.</p>
<p><b>Example</b>. Make a query for the device clock frequency.</p>
<div class="fragment"><div class="line"><a class="code" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7">canStatus</a> stat;</div><div class="line"><a class="code" href="structkv_clock_info.html">kvClockInfo</a> clockInfo;</div><div class="line"><span class="keywordtype">int</span> frequency;</div><div class="line"></div><div class="line">stat = <a class="code" href="group___c_a_n.html#ga909e5c14b09fe76bad280475138d503e">canGetHandleData</a>(hnd, <a class="code" href="canlib_8h.html#a40c7c5a86334adcc799cd78696deca2e">canCHANNELDATA_CLOCK_INFO</a>, &amp;clockInfo, <span class="keyword">sizeof</span>(clockInfo));</div><div class="line"><span class="keywordflow">if</span> (stat != canOK) {</div><div class="line">      printf(<span class="stringliteral">&quot;Close failed.&quot;</span>);</div><div class="line">}</div><div class="line">frequency = clockInfo.<a class="code" href="structkv_clock_info.html#afda10a8365f279d4d95a406787507bde">numerator</a> / clockInfo.<a class="code" href="structkv_clock_info.html#a6d7a01ea2b2b71b529a024b1a4617e3f">denominator</a> * pow(10, clockInfo.<a class="code" href="structkv_clock_info.html#a67810cb57a3edc799ac9b23ebbe59457">power_of_ten</a>);</div><div class="line">printf(<span class="stringliteral">&quot;clock frequency = %d\n&quot;</span>, frequency);</div></div><!-- fragment --><p><b>Example</b>. Print the upper and lower bit timing limits for a device associated with a specific CAN channel.</p>
<div class="fragment"><div class="line"><a class="code" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7">canStatus</a> stat;</div><div class="line"><a class="code" href="structkv_bus_param_limits.html">kvBusParamLimits</a> limits;</div><div class="line"></div><div class="line">stat = <a class="code" href="group__can__general.html#gab9552d1a588b0dbc144b097acba017b2">canGetChannelData</a>(channel, <a class="code" href="canlib_8h.html#ad4a719c4336ae1ec409bc835a9321f05">canCHANNELDATA_BUS_PARAM_LIMITS</a>, &amp;limits, <span class="keyword">sizeof</span>(limits));</div><div class="line"><span class="keywordflow">if</span> (stat != canOK) {</div><div class="line">     printf(<span class="stringliteral">&quot;Get bus parameter limits limits failed.&quot;</span>);</div><div class="line">}</div><div class="line"></div><div class="line">printf (<span class="stringliteral">&quot;\n------- Arbitration limits -------\n&quot;</span>);</div><div class="line">printf (<span class="stringliteral">&quot;   phase1      min: %d   max: %d\n&quot;</span>, limits.<a class="code" href="structkv_bus_param_limits.html#a704d465cdedf10c17c6e61884b6d76ff">arbitration_min</a>.<a class="code" href="structkv_bus_params_tq.html#aa8c2aacf694615ddaff84e31b31ae0ff">phase1</a>, limits.<a class="code" href="structkv_bus_param_limits.html#a6d10a8e3c78ce93fa4c4c2ab206a817d">arbitration_max</a>.<a class="code" href="structkv_bus_params_tq.html#aa8c2aacf694615ddaff84e31b31ae0ff">phase1</a>);</div><div class="line">printf (<span class="stringliteral">&quot;   phase2      min: %d   max: %d\n&quot;</span>, limits.<a class="code" href="structkv_bus_param_limits.html#a704d465cdedf10c17c6e61884b6d76ff">arbitration_min</a>.<a class="code" href="structkv_bus_params_tq.html#a87167f9802ef5563e4236d5710e1b65b">phase2</a>, limits.<a class="code" href="structkv_bus_param_limits.html#a6d10a8e3c78ce93fa4c4c2ab206a817d">arbitration_max</a>.<a class="code" href="structkv_bus_params_tq.html#a87167f9802ef5563e4236d5710e1b65b">phase2</a>);</div><div class="line">printf (<span class="stringliteral">&quot;   sjw         min: %d   max: %d\n&quot;</span>, limits.<a class="code" href="structkv_bus_param_limits.html#a704d465cdedf10c17c6e61884b6d76ff">arbitration_min</a>.<a class="code" href="structkv_bus_params_tq.html#a3b769dc9a0e203dea3cc931bdb304377">sjw</a>, limits.<a class="code" href="structkv_bus_param_limits.html#a6d10a8e3c78ce93fa4c4c2ab206a817d">arbitration_max</a>.<a class="code" href="structkv_bus_params_tq.html#a3b769dc9a0e203dea3cc931bdb304377">sjw</a>);</div><div class="line">printf (<span class="stringliteral">&quot;   prop        min: %d   max: %d\n&quot;</span>, limits.<a class="code" href="structkv_bus_param_limits.html#a704d465cdedf10c17c6e61884b6d76ff">arbitration_min</a>.<a class="code" href="structkv_bus_params_tq.html#a4a8f6c91eefb9c6bf448592aac44153d">prop</a>, limits.<a class="code" href="structkv_bus_param_limits.html#a6d10a8e3c78ce93fa4c4c2ab206a817d">arbitration_max</a>.<a class="code" href="structkv_bus_params_tq.html#a4a8f6c91eefb9c6bf448592aac44153d">prop</a>);</div><div class="line">printf (<span class="stringliteral">&quot;   prescaler   min: %d   max: %d\n&quot;</span>, limits.<a class="code" href="structkv_bus_param_limits.html#a704d465cdedf10c17c6e61884b6d76ff">arbitration_min</a>.<a class="code" href="structkv_bus_params_tq.html#af263c600d546b48e74f8f7ac7a891533">prescaler</a>, limits.<a class="code" href="structkv_bus_param_limits.html#a6d10a8e3c78ce93fa4c4c2ab206a817d">arbitration_max</a>.<a class="code" href="structkv_bus_params_tq.html#af263c600d546b48e74f8f7ac7a891533">prescaler</a>);</div><div class="line">printf (<span class="stringliteral">&quot;\n---------- Data limits -----------\n&quot;</span>);</div><div class="line">printf (<span class="stringliteral">&quot;   phase1      min: %d   max: %d\n&quot;</span>, limits.<a class="code" href="structkv_bus_param_limits.html#aca75b9806920539ceea834b9ca411495">data_min</a>.<a class="code" href="structkv_bus_params_tq.html#aa8c2aacf694615ddaff84e31b31ae0ff">phase1</a>, limits.<a class="code" href="structkv_bus_param_limits.html#ac989469cbc0ab9cae6da7801f11d4be0">data_max</a>.<a class="code" href="structkv_bus_params_tq.html#aa8c2aacf694615ddaff84e31b31ae0ff">phase1</a>);</div><div class="line">printf (<span class="stringliteral">&quot;   phase2      min: %d   max: %d\n&quot;</span>, limits.<a class="code" href="structkv_bus_param_limits.html#aca75b9806920539ceea834b9ca411495">data_min</a>.<a class="code" href="structkv_bus_params_tq.html#a87167f9802ef5563e4236d5710e1b65b">phase2</a>, limits.<a class="code" href="structkv_bus_param_limits.html#ac989469cbc0ab9cae6da7801f11d4be0">data_max</a>.<a class="code" href="structkv_bus_params_tq.html#a87167f9802ef5563e4236d5710e1b65b">phase2</a>);</div><div class="line">printf (<span class="stringliteral">&quot;   sjw         min: %d   max: %d\n&quot;</span>, limits.<a class="code" href="structkv_bus_param_limits.html#aca75b9806920539ceea834b9ca411495">data_min</a>.<a class="code" href="structkv_bus_params_tq.html#a3b769dc9a0e203dea3cc931bdb304377">sjw</a>, limits.<a class="code" href="structkv_bus_param_limits.html#ac989469cbc0ab9cae6da7801f11d4be0">data_max</a>.<a class="code" href="structkv_bus_params_tq.html#a3b769dc9a0e203dea3cc931bdb304377">sjw</a>);</div><div class="line">printf (<span class="stringliteral">&quot;   prop        min: %d   max: %d\n&quot;</span>, limits.<a class="code" href="structkv_bus_param_limits.html#aca75b9806920539ceea834b9ca411495">data_min</a>.<a class="code" href="structkv_bus_params_tq.html#a4a8f6c91eefb9c6bf448592aac44153d">prop</a>, limits.<a class="code" href="structkv_bus_param_limits.html#ac989469cbc0ab9cae6da7801f11d4be0">data_max</a>.<a class="code" href="structkv_bus_params_tq.html#a4a8f6c91eefb9c6bf448592aac44153d">prop</a>);</div><div class="line">printf (<span class="stringliteral">&quot;   prescaler   min: %d   max: %d\n&quot;</span>, limits.<a class="code" href="structkv_bus_param_limits.html#aca75b9806920539ceea834b9ca411495">data_min</a>.<a class="code" href="structkv_bus_params_tq.html#af263c600d546b48e74f8f7ac7a891533">prescaler</a>, limits.<a class="code" href="structkv_bus_param_limits.html#ac989469cbc0ab9cae6da7801f11d4be0">data_max</a>.<a class="code" href="structkv_bus_params_tq.html#af263c600d546b48e74f8f7ac7a891533">prescaler</a>);</div></div><!-- fragment --><p>Obtain channel capabilities by passing argument <a class="el" href="canlib_8h.html#a7eeb70e7c666f629ca3762f4692469ae">canCHANNELDATA_CHANNEL_CAP</a> and extended capabilities using flag <a class="el" href="canlib_8h.html#ae8f3ade70e6718ccca7d914b251d0d2c">canCHANNELDATA_CHANNEL_CAP_EX</a>. Support for specific capabilities are tested by a bitwise AND operation with corresponding capability flags <a class="el" href="canlib_8h.html#canCHANNEL_CAP_xxx">canCHANNEL_CAP_xxx</a>, and <a class="el" href="canlib_8h.html#canCHANNEL_CAP_EX_xxx">canCHANNEL_CAP_EX_xxx</a>.</p>
<p><b>Example</b>. Check if channel has support for CAN FD, and setting bus speed and bit timing parameters using <a class="el" href="group___c_a_n.html#ga50f169c6f9dd6df93b17c322e8e4fd00">canSetBusParamsTq()</a>.</p>
<div class="fragment"><div class="line"><a class="code" href="canstat_8h.html#a52b5e5c71832b0bd3c6a5b1fd48583e7">canStatus</a> stat;</div><div class="line">uint32_t cap;</div><div class="line">uint64_t cap_ex[2];</div><div class="line"></div><div class="line">stat = <a class="code" href="group___c_a_n.html#ga909e5c14b09fe76bad280475138d503e">canGetHandleData</a>(hnd, <a class="code" href="canlib_8h.html#a7eeb70e7c666f629ca3762f4692469ae">canCHANNELDATA_CHANNEL_CAP</a>, &amp;cap, <span class="keyword">sizeof</span>(cap));</div><div class="line"> <span class="keywordflow">if</span> (stat != canOK) {</div><div class="line">      printf(<span class="stringliteral">&quot;Get channel capabilities failed.&quot;</span>);</div><div class="line"> }</div><div class="line"> <span class="keywordflow">if</span> (cap &amp; canCHANNEL_CAP_CAN_FD) {</div><div class="line">      printf(<span class="stringliteral">&quot;Channel has support for CAN FD.\n&quot;</span>);</div><div class="line"> }</div><div class="line"></div><div class="line">stat = <a class="code" href="group___c_a_n.html#ga909e5c14b09fe76bad280475138d503e">canGetHandleData</a>(hnd, <a class="code" href="canlib_8h.html#ae8f3ade70e6718ccca7d914b251d0d2c">canCHANNELDATA_CHANNEL_CAP_EX</a>, &amp;cap_ex, <span class="keyword">sizeof</span>(cap_ex));</div><div class="line"><span class="keywordflow">if</span> (stat != canOK) {</div><div class="line">      printf(<span class="stringliteral">&quot;Get extended channel capabilities failed.&quot;</span>);</div><div class="line"> }</div><div class="line"><span class="keywordflow">if</span> (cap_ex[0] &amp; canCHANNEL_CAP_EX_BUSPARAMS_TQ) {</div><div class="line">  printf(<span class="stringliteral">&quot;Channel has support for setting bitrate using canSetBusParamsTq().\n&quot;</span>);</div><div class="line">}</div></div><!-- fragment --><h1><a class="anchor" id="section_user_guide_init_bit_rate_can_tq"></a>
Set CAN Bitrate</h1>
<p>After opening a channel in classic CAN mode (see <a class="el" href="page_user_guide_chips_channels.html#section_user_guide_init_sel_channel_can">Open as CAN</a>), the bus speed can be set either by manually specifying bit timing parameters, or by using predefined bitrate constants.</p>
<h2><a class="anchor" id="section_user_guide_init_bit_rate_can_specify_tq"></a>
Specifying Bit Timing Parameters</h2>
<p>Use <a class="el" href="group___c_a_n.html#ga50f169c6f9dd6df93b17c322e8e4fd00">canSetBusParamsTq()</a> to set the bit timing parameters on the CAN bus. Bit timing parameters are packaged in a struct <a class="el" href="structkv_bus_params_tq.html">kvBusParamsTq</a>, note that the synchronization segment is excluded as it is always one time quantum long.</p>
<p><b>Example</b>. To set the bus speed to 500 kbit/s on a CAN device with an 80 MHz oscillator:</p>
<div class="fragment"><div class="line"><a class="code" href="structkv_bus_params_tq.html">kvBusParamsTq</a> params = { 8, 2, 2, 1, 3, 20 };</div><div class="line">stat = <a class="code" href="group___c_a_n.html#ga50f169c6f9dd6df93b17c322e8e4fd00">canSetBusParamsTq</a>(hnd, params);</div><div class="line"><span class="keywordflow">if</span> (stat != canOK) {</div><div class="line">  printf(<span class="stringliteral">&quot;canSetBusParamsTq failed, status=%d\n&quot;</span>, stat);</div><div class="line">  exit(1);</div><div class="line">}</div></div><!-- fragment --><p>In the example a prescaler of 20 is used, resulting in each bit comprising of 160 time quanta (8 * 20). The nominal bus speed is given by 80 * 10^6 / (20 * 8) = 500 * 10^3.</p>
<p>If uncertain how to calculate bit timing parameters, appropriate values can be acquired using the <a href="https://www.kvaser.com/support/calculators/can-fd-bit-timing-calculator/" target="_blank">Bit Timing Calculator for CAN FD</a>. Note that in classic CAN mode, only the nominal bus parameters are of concern when using the Bus Bit Timing Calculator.</p>
<h2><a class="anchor" id="section_user_guide_init_bit_rate_can_predefined"></a>
Using Predefined Bitrate Constants</h2>
<p>For users that not are interested in specifying individual bit timing parameters, CANlib also provides a set of default parameter settings for the most common bus speeds through the <a class="el" href="canlib_8h.html#canBITRATE_xxx">canBITRATE_xxx</a> constants. To set the bus speed using predefined bit rates, use <a class="el" href="group___c_a_n.html#ga7eb8c2e92cfae57e7ec5031818524301">canSetBusParams()</a> with a <a class="el" href="canlib_8h.html#canBITRATE_xxx">canBITRATE_xxx</a> constant as the second argument, and all trailing arguments set to zero.</p>
<p><b>Example</b>. Setting the bus speed to 500 kbit/s:</p>
<div class="fragment"><div class="line">stat = <a class="code" href="group___c_a_n.html#ga7eb8c2e92cfae57e7ec5031818524301">canSetBusParams</a>(hnd, <a class="code" href="canlib_8h.html#ae72ee3c12379c4817de3b53c7cc6d89c">canBITRATE_500K</a>, 0, 0, 0, 0, 0);</div><div class="line"><span class="keywordflow">if</span> (stat != canOK) {</div><div class="line">    printf(<span class="stringliteral">&quot;canSetBusParams failed, status=%d\n&quot;</span>, stat);</div><div class="line">    exit(1);</div><div class="line">}</div></div><!-- fragment --><p><b>Available predefined bitrate constants with corresponding bit timing parameters for a CAN device with an 80 MHz oscillator.</b> <sup>[<a class="el" href="page_user_guide_chips_channels.html#clock_freq_footnote">1</a>]</sup> </p><table class="doxtable">
<tr>
<td></td><th>tq</th><th>phase1</th><th>phase2</th><th>sjw</th><th>prop</th><th>prescaler</th><th>Sample point</th><th>Bitrate </th></tr>
<tr>
<th>canBITRATE_10K</th><td>16</td><td>4</td><td>4</td><td>1</td><td>7</td><td>500</td><td>75%</td><td>10 kbit/s </td></tr>
<tr>
<th>canBITRATE_50K</th><td>16</td><td>4</td><td>4</td><td>1</td><td>7</td><td>100</td><td>75%</td><td>50 kbit/s </td></tr>
<tr>
<th>canBITRATE_62K</th><td>16</td><td>4</td><td>4</td><td>1</td><td>7</td><td>80</td><td>75%</td><td>62 kbit/s </td></tr>
<tr>
<th>canBITRATE_83K</th><td>8</td><td>2</td><td>2</td><td>2</td><td>3</td><td>120</td><td>75%</td><td>83 kbit/s </td></tr>
<tr>
<th>canBITRATE_100K</th><td>16</td><td>4</td><td>4</td><td>1</td><td>7</td><td>50</td><td>75%</td><td>100 kbit/s </td></tr>
<tr>
<th>canBITRATE_125K</th><td>16</td><td>4</td><td>4</td><td>1</td><td>7</td><td>40</td><td>75%</td><td>125 kbit/s </td></tr>
<tr>
<th>canBITRATE_250K</th><td>8</td><td>2</td><td>2</td><td>1</td><td>3</td><td>40</td><td>75%</td><td>250 kbit/s </td></tr>
<tr>
<th>canBITRATE_500K</th><td>8</td><td>2</td><td>2</td><td>1</td><td>3</td><td>20</td><td>75%</td><td>500 kbit/s </td></tr>
<tr>
<th>canBITRATE_1M</th><td>8</td><td>2</td><td>2</td><td>1</td><td>3</td><td>10</td><td>75%</td><td>1 Mbit/s  </td></tr>
</table>
<p>For bus speeds other than the predefined <a class="el" href="canlib_8h.html#canBITRATE_xxx">canBITRATE_xxx</a> constants, bit timing parameters have to be specified manually.</p>
<h1><a class="anchor" id="section_user_guide_init_bit_rate_canfd_tq"></a>
Set CAN FD Bitrate</h1>
<p>After opening a channel in CAN FD mode (see <a class="el" href="page_user_guide_chips_channels.html#section_user_guide_init_sel_channel_canfd">Open as CAN FD</a>), the bus speed can be set either by specifying bit timing parameters, or by using predefined bitrate constants.</p>
<h2><a class="anchor" id="section_user_guide_init_bit_rate_canfd_specify_tq"></a>
Specifying Bit Timing Parameters</h2>
<p>Use <a class="el" href="group___c_a_n.html#ga4beeb28ede2e21a2988076e66f873723">canSetBusParamsFdTq()</a> to set the bit timing parameters on the CAN bus in CAN FD mode. Bit timing parameters for both the arbitration and data phases need to be set using two separate <a class="el" href="structkv_bus_params_tq.html">kvBusParamsTq</a> structs.</p>
<p><b>Example</b>. Set the arbitration bitrate to 500 kbit/s and the data phase bitrate to 1000 kbit/s, with sampling points at 80% on a device with an 80 MHz oscillator.</p>
<div class="fragment"><div class="line"><a class="code" href="structkv_bus_params_tq.html">kvBusParamsTq</a> paramsArb = { 80, 16, 16, 16, 47, 2 };</div><div class="line"><a class="code" href="structkv_bus_params_tq.html">kvBusParamsTq</a> paramsDat = { 40, 31, 8, 8, 0, 2 };</div><div class="line">stat = <a class="code" href="group___c_a_n.html#ga4beeb28ede2e21a2988076e66f873723">canSetBusParamsFdTq</a>(hnd, paramsArb, paramsDat);</div><div class="line"><span class="keywordflow">if</span> (stat != canOK) {</div><div class="line">  printf(<span class="stringliteral">&quot;canSetBusParamsFdTq failed, status=%d\n&quot;</span>, stat);</div><div class="line">  exit(1);</div><div class="line">}</div></div><!-- fragment --><p>If uncertain how to calculate bit timing parameters, appropriate values can be acquired using the <a href="https://www.kvaser.com/support/calculators/can-fd-bit-timing-calculator/" target="_blank">Bit Timing Calculator for CAN FD</a></p>
<h2><a class="anchor" id="section_user_guide_init_bit_rate_canfd_predefined"></a>
Using Predefined Bitrate Constants</h2>
<p>For users that are not interested in specifying individual bit timing parameters, CANlib provides a set of default parameter settings for the most common bus speeds through the <a class="el" href="canlib_8h.html#canFD_BITRATE_xxx">canFD_BITRATE_xxx</a> constants. Use <a class="el" href="group___c_a_n.html#ga7eb8c2e92cfae57e7ec5031818524301">canSetBusParams()</a> to set the arbitration phase bus speed, and <a class="el" href="group___c_a_n.html#gafcd85fbac103dcb123f4cd609be6fa14">canSetBusParamsFd()</a> to set the data phase bus speed.</p>
<p><b>Example</b>. Set the arbitration phase bitrate to 500 kbit/s, with sampling point at 80% and the data phase bitrate to 1000 kbit/s, with sampling point at 80%.</p>
<div class="fragment"><div class="line">stat1 = <a class="code" href="group___c_a_n.html#ga7eb8c2e92cfae57e7ec5031818524301">canSetBusParams</a>(hnd, <a class="code" href="canlib_8h.html#a71dec626b7de7ddd18daf93e535902f4">canFD_BITRATE_500K_80P</a>, 0, 0, 0, 0, 0);</div><div class="line">stat2 = <a class="code" href="group___c_a_n.html#gafcd85fbac103dcb123f4cd609be6fa14">canSetBusParamsFd</a>(hnd, <a class="code" href="canlib_8h.html#a3a93c64ba76ebe3c5e525d4dfa4ade8d">canFD_BITRATE_1M_80P</a>, 0, 0, 0);</div><div class="line"><span class="keywordflow">if</span> (stat1 != canOK || stat2 canOK) {</div><div class="line">  printf(<span class="stringliteral">&quot;Setting bus parameters failed, stat1s=%d stat2=%d\n&quot;</span>, stat1, stat2);</div><div class="line">  exit(1);</div><div class="line">}</div></div><!-- fragment --><p><b>Available predefined bitrate constants with corresponding bit timing parameters for a CAN FD device with an 80 MHz oscillator.</b> <sup>[<a class="el" href="page_user_guide_chips_channels.html#clock_freq_footnote">1</a>]</sup> </p><table class="doxtable">
<tr>
<td></td><th>tq</th><th>phase1</th><th>phase2</th><th>sjw</th><th>prop</th><th>prescaler</th><th>Sample point</th><th>Bitrate </th></tr>
<tr>
<th>canFD_BITRATE_500K_80P</th><td>40</td><td>8</td><td>8</td><td>8</td><td>23</td><td>4</td><td>80%</td><td>500 kbt/s </td></tr>
<tr>
<th>canFD_BITRATE_1M_80P</th><td>40</td><td>8</td><td>8</td><td>8</td><td>23</td><td>2</td><td>80%</td><td>1 Mbit/s </td></tr>
<tr>
<th>canFD_BITRATE_2M_80P</th><td>20</td><td>8</td><td>4</td><td>4</td><td>7</td><td>2</td><td>80%</td><td>2 Mbit/s </td></tr>
<tr>
<th>canFD_BITRATE_4M_80P</th><td>10</td><td>7</td><td>2</td><td>2</td><td>0</td><td>2</td><td>80%</td><td>4 Mbit/s </td></tr>
<tr>
<th>canFD_BITRATE_8M_60P</th><td>5</td><td>2</td><td>2</td><td>1</td><td>0</td><td>2</td><td>60%</td><td>8 Mbit/s  </td></tr>
</table>
<p>For bus speeds other than the predefined <a class="el" href="canlib_8h.html#canFD_BITRATE_xxx">canFD_BITRATE_xxx</a> constants, bit timing parameters have to be specified manually.</p>
<h1><a class="anchor" id="section_user_guide_init_driver_modes"></a>
CAN Driver Modes</h1>
<p>Use <a class="el" href="group___c_a_n.html#gafca31590718ac7101d065b0c18b2410e">canSetBusOutputControl()</a> to set the bus driver mode. This is usually set to <a class="el" href="canlib_8h.html#ae5d980394050f52fd4af8f8ca75a4bca">canDRIVER_NORMAL</a> to obtain the standard push-pull type of driver. Some controllers also support <a class="el" href="canlib_8h.html#ab82a818e60cddf4c65c54d42a474a023">canDRIVER_SILENT</a> which makes the controller receive only, not transmit anything, not even ACK bits. This might be handy for e.g. when listening to a CAN bus without interfering.</p>
<div class="fragment"><div class="line">stat = <a class="code" href="group___c_a_n.html#gafca31590718ac7101d065b0c18b2410e">canSetBusOutputControl</a>(canDRIVER_SILENT);</div></div><!-- fragment --><p><a class="el" href="canlib_8h.html#ae5d980394050f52fd4af8f8ca75a4bca">canDRIVER_NORMAL</a> is set by default.</p>
<h1><a class="anchor" id="code_sample"></a>
Code Sample</h1>
<p>See <a class="el" href="how-to_2c_2open_channels_8c-example.html">how-to/c/openChannels.c</a> for code sample.</p>
<h1><a class="anchor" id="section_user_guide_init_bit_rate_legacy"></a>
Legacy Functions</h1>
<p>The following functions are still supported in canlib.</p>
<h2><a class="anchor" id="section_user_guide_init_bit_rate_can"></a>
Set CAN Bitrate</h2>
<p><a class="el" href="group___c_a_n.html#ga7eb8c2e92cfae57e7ec5031818524301">canSetBusParams()</a> can be used to set CAN bus parameters, including bitrate, the position of the sampling point etc, they are also described in most CAN controller data sheets. Depending on device and installed firmware, the requested parameters may be subject to scaling in order to accommodate device specific restrictions. As such, reading back bus parameters using <a class="el" href="group___c_a_n.html#gaf2a734c0486030610389331685a3827a">canGetBusParams()</a> can return bus parameter settings different than the ones supplied. Note however, that a successful call to <a class="el" href="group___c_a_n.html#ga7eb8c2e92cfae57e7ec5031818524301">canSetBusParams()</a> will always result in the requested bit rate being set on the bus, along with bus parameters that for all intents and purposes are equivalent to the ones requested.</p>
<p><b>Example</b>. Set the speed to 125 kbit/s, each bit comprising 8 (= 1 + 4 + 3) quanta, the sampling point occurs at 5/8 of a bit; SJW = 1; one sampling point.</p>
<div class="fragment"><div class="line">stat = <a class="code" href="group___c_a_n.html#ga7eb8c2e92cfae57e7ec5031818524301">canSetBusParams</a>(hnd, 125000, 4, 3, 1, 1, 0);</div><div class="line"><span class="keywordflow">if</span> (stat != canOK) {</div><div class="line">  printf(<span class="stringliteral">&quot;canSetBusParams failed, status=%d\n&quot;</span>, stat);</div><div class="line">  exit(1);</div><div class="line">}</div></div><!-- fragment --><p><b>Example</b>. Set the speed to 111111 kbit/s, the sampling point to 75%, the SJW to 2 and the number of samples to 1:</p>
<div class="fragment"><div class="line">stat = <a class="code" href="group___c_a_n.html#ga7eb8c2e92cfae57e7ec5031818524301">canSetBusParams</a>(hnd, 111111, 5, 2, 2, 1, 0);</div></div><!-- fragment --><p>For full bit timing control, use <a class="el" href="group___c_a_n.html#ga50f169c6f9dd6df93b17c322e8e4fd00">canSetBusParamsTq()</a> instead.</p>
<h2><a class="anchor" id="section_user_guide_init_bit_rate_canfd"></a>
Set CAN FD Bitrate</h2>
<p>After a channel has been opened in CAN FD mode, <a class="el" href="group___c_a_n.html#ga7eb8c2e92cfae57e7ec5031818524301">canSetBusParams()</a> and <a class="el" href="group___c_a_n.html#gafcd85fbac103dcb123f4cd609be6fa14">canSetBusParamsFd()</a> can be used to set the arbitration and data phase bitrates respectively. Depending on device and installed firmware, the requested parameters may be subject to scaling in order to accommodate device specific restrictions. As such, reading back bus parameters using <a class="el" href="group___c_a_n.html#gab620a5cd6249e2e53cf2a0099e7e8685">canGetBusParamsFd()</a> can return bus parameter settings different than the ones supplied. Note however, that a successful call to <a class="el" href="group___c_a_n.html#gafcd85fbac103dcb123f4cd609be6fa14">canSetBusParamsFd()</a> will always result in the requested bit rate being set on the bus, along with bus parameters that for all intents and purposes are equivalent to the ones requested.</p>
<p><b>Example</b>. Set the nominal bitrate to 500 kbit/s and the data phase bitrate to 1000 kbit/s, with sampling points at 80%.</p>
<div class="fragment"><div class="line">stat1 = <a class="code" href="group___c_a_n.html#ga7eb8c2e92cfae57e7ec5031818524301">canSetBusParams</a>(hnd, 500000L, 63, 16, 16, 1, 0);</div><div class="line">stat2 = <a class="code" href="group___c_a_n.html#gafcd85fbac103dcb123f4cd609be6fa14">canSetBusParamsFd</a>(hnd, 1000000L, 31, 8, 8);</div><div class="line"><span class="keywordflow">if</span> (stat1 != canOK || stat2 != canOK) {</div><div class="line">  printf(<span class="stringliteral">&quot;Setting bus parameters failed, stat1=%d, stat2=%d\n&quot;</span>, stat1, stat2);</div><div class="line">  exit(1);</div><div class="line">}</div></div><!-- fragment --><p>For full bit timing control, use <a class="el" href="group___c_a_n.html#ga4beeb28ede2e21a2988076e66f873723">canSetBusParamsFdTq()</a> instead.</p>
<hr/>
<p><a class="anchor" id="clock_freq_footnote"></a><b>[1]</b> <em>See <a class="el" href="page_user_guide_chips_channels.html#section_user_guide_check_channel_capabilities">Check Channel Capabilities</a> for information on clock frequency.</em> </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.8.13-->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="navelem"><a class="el" href="page_canlib.html">CAN bus API (CANlib)</a></li>
    <li class="footer"> (canlib 5.38) Tue Feb 15 2022</li>
  </ul>
</div>
</body>
</html>
